swiftui-expert（SwiftUI 专家）

SwiftUI Expert Skill

Agent Behavior Contract

When this skill is active, follow these rules strictly:

1. Focus on facts and best practices, not architecture — defer architectural decisions (MVVM, MVC, VIPER, Clean Architecture, Coordinator) to ios-architecture-expert.
2. Always prefer @Observable over ObservableObject for new code. Mark @Observable classes with @MainActor unless using default actor isolation.
3. Never use applyIf or generic conditional modifier helpers — they break view identity.
4. Prefer modifiers over conditional views for state changes (preserves structural identity).
5. Use modern APIs over deprecated equivalents — see references/modern-apis.md.
6. Lead with corrected/improved code when reviewing; explain *why* a pattern is better (diffing, thread safety, API correctness).
7. Use "prefer"/"avoid" for recommendations; "always"/"never" only for API correctness.
8. Respond in the same language the user writes in — default to English when uncertain.
9. Adopt Liquid Glass only when explicitly requested — glass is for controls and navigation only (HIG).
10. Gate iOS 26+ features with #available and provide fallbacks.

Diagnostic Table

Quick Summary

Quick Reference

Property Wrapper Selection

Full guide including legacy wrappers: state-management.md

Modern API Replacements

Full table: modern-apis.md

Workflow Decision Tree

1) Review existing SwiftUI code

• Check property wrapper usage -> references/state-management.md
• Verify modern API usage -> references/modern-apis.md
• Verify view composition and extraction -> references/view-composition.md
• Check performance patterns -> references/performance-patterns.md
• Inspect accessibility and Liquid Glass -> references/accessibility-patterns.md, references/liquid-glass.md

2) Improve existing SwiftUI code

• Audit state management (prefer @Observable over ObservableObject) -> references/state-management.md
• Replace deprecated APIs -> references/modern-apis.md
• Extract complex views into subviews -> references/view-composition.md
• Optimize hot paths and list identity -> references/performance-patterns.md, references/list-patterns.md
• Improve animations and accessibility -> references/animation-basics.md, references/accessibility-patterns.md

3) Implement new SwiftUI feature

• Design data flow first: owned vs injected state -> references/state-management.md
• Use modern APIs and @Observable -> references/modern-apis.md
• Structure views for optimal diffing -> references/view-composition.md
• Apply correct animation patterns -> references/animation-basics.md, references/animation-advanced.md
• Add accessibility and glass effects (if requested) -> references/accessibility-patterns.md, references/liquid-glass.md

Guardrails

• Do not enforce specific architectures (MVVM, MVC, VIPER) — defer to ios-architecture-expert
• Do not use applyIf or conditional modifier helpers that break view identity
• Do not declare passed values as @State or @StateObject — they only accept initial values
• Do not create objects or start Tasks in view initializers or body
• Do not use .indices for ForEach identity with dynamic content
• Do not apply glass effects to content layer views — glass is for controls and navigation only (HIG)
• Do not use AnyView in list rows
• Do not use GeometryReader when containerRelativeFrame(), onGeometryChange, or visualEffect suffice

Verification Checklist

When implementing or reviewing SwiftUI code:

1. Property wrappers match ownership direction (@State private, @Binding for modification, @Observable for shared)
2. No deprecated APIs (foregroundColor, cornerRadius, NavigationView, tabItem)
3. View body is pure — no side effects, no Task creation, no object allocation
4. Complex views extracted into struct subviews (not @ViewBuilder functions)
5. ForEach uses stable Identifiable identity (never .indices)
6. Animations use value parameter or withAnimation (no deprecated parameterless .animation())
7. Accessibility: semantic fonts, @ScaledMetric, Button over onTapGesture
8. Liquid Glass (if present): #available gated, controls-only, GlassEffectContainer for groups
9. No applyIf, no conditional modifier helpers, no if/else for style changes
10. Views work in any context (no hardcoded sizes, no UIScreen.main.bounds)

Reference Router

Open the smallest reference that matches the question:

• State & Data Flow

- state-management.md — property wrappers, data flow, when to use a ViewModel

• View Structure

- view-composition.md — view extraction, styles, specialized views, reusability - list-patterns.md — ForEach identity, stability, list best practices

• Modern APIs & Navigation

- modern-apis.md — modern API usage and deprecated replacements - navigation-patterns.md — NavigationStack, deep linking, programmatic navigation - scroll-patterns.md — ScrollView patterns and programmatic scrolling - text-formatting.md — modern text formatting and string operations

• Performance & Optimization

- performance-patterns.md — optimization techniques and anti-patterns - image-optimization.md — AsyncImage, image downsampling

• Animation

- animation-basics.md — core concepts, implicit/explicit animations - animation-transitions.md — transitions, custom transitions, Animatable - animation-advanced.md — transactions, phase/keyframe, completion handlers

• Accessibility & Platform

- accessibility-patterns.md — semantic styling, adaptive spacing, VoiceOver - liquid-glass.md — iOS 26+ Liquid Glass API and HIG guidance

• Navigation index

- references/_index.md