AgentSkillsCN

swiftui

适用于为 iOS、iPadOS、macOS 或 visionOS 构建 SwiftUI 界面时使用。触发因素包括 Liquid Glass 的应用、SwiftUI 动画与过渡效果、布局模式、状态管理、设计令牌、性能优化、SwiftUI 的无障碍设计，以及打造“苹果级”的 UI 质量。

SKILL.md
--- frontmatter
name: swiftui
description: Use when building SwiftUI interfaces for iOS, iPadOS, macOS, or visionOS. Triggers on Liquid Glass adoption, SwiftUI animation/transitions, layout patterns, state management, design tokens, performance optimization, accessibility in SwiftUI, or creating "Apple-level" UI quality.

SwiftUI Excellence Playbook

Tactical guide for designing and building world-class SwiftUI interfaces—the kind that feel at home next to Apple's own apps.

Six Non-Negotiables

  1. •Content first — UI is a frame, not the painting
  2. •System components unless measured reason not to — buy accessibility, platform behavior, design updates for free
  3. •Design for states, not screens — every screen handles: loading, empty, error, offline, partial, permission denied
  4. •Accessibility is a constraint — Dynamic Type, VoiceOver, Reduce Motion/Transparency, Increased Contrast
  5. •Performance is a feature — "feels instant" interactions, instrument when hitches occur
  6. •Coherence over cleverness — best interfaces feel inevitable

Quick Reference: ADA Rubric

CategoryRequirement
DelightMicro-delight at success moments only, never reduces clarity
InnovationIn discovery, state communication, simplifying complexity
InteractionPredictable, direct, forgiving, platform-appropriate
InclusivityDynamic Type XXL+, VoiceOver, no color-only meaning, reduced motion
VisualsConsistent rhythm, coherent materials, restrained tint

Design Workflow (Step-by-Step)

  1. •Define experience — 10-line spec: goal, primary action, states, edge cases, platforms
  2. •Sketch IA — TabView vs NavigationSplitView vs deep navigation
  3. •Design hierarchy — one hero, one primary CTA per moment, progressive disclosure
  4. •Build tokens first — spacing, radius, typography, motion, colors
  5. •Build components — cards, rows, buttons, empty states, filters
  6. •Integrate structure — NavigationStack, NavigationSplitView, TabView, Sheets
  7. •Add motion — only what improves comprehension and causality
  8. •Accessibility + performance pass — Dynamic Type, VoiceOver, Instruments

Liquid Glass Quick Rules (iOS 26+)

Do:

  • •Use glass for navigation/control layer floating above content
  • •Group nearby glass in GlassEffectContainer
  • •Use glassEffect(.interactive) for custom controls
  • •Use glassEffectID for morphing transitions

Don't:

  • •Glass on content layer (tables, documents)
  • •Glass on glass stacking
  • •Tint everything — only primary actions/meaning
  • •Custom backgrounds behind toolbars (let system handle scroll edge effects)

Layout Essentials

ContainerUse For
ListLarge datasets, selection, swipe actions, edit mode
ScrollView + LazyVStackCustom surfaces, cards, mixed content
GridForms, settings, dense structured layouts
LazyVGridResponsive galleries
NavigationSplitViewiPad/Mac hierarchical apps
NavigationStackDeep navigation flows

Animation Principles

  • •Motion communicates causality, hierarchy, continuity
  • •State-driven animation, not imperative choreography
  • •Springs for organic UI, ease-in/out for fades
  • •Custom transitions for signature moments only
  • •Always provide Reduce Motion fallback

Performance Rules

RuleImplementation
Body must be cheapNo sorting, filtering, formatting, I/O in body
Stable identityForEach(items, id: \.id) not \.self, no UUID() in body
Dependency hygieneKeep @State local, pass Binding not whole model
InstrumentUse SwiftUI instrument (Instruments 26) for hitches

Accessibility Checklist

  • • System text styles, no clipping at XXL+
  • • Layout adapts (stacks turn vertical, rows multi-line)
  • • VoiceOver labels/hints on non-obvious controls
  • • Focus order matches reading order
  • • 44×44pt minimum touch targets
  • • Reduced Motion removes parallax, uses opacity
  • • Reduced Transparency increases separation

Component Primitives (Build These)

  1. •Screen scaffold
  2. •Section header
  3. •Card surface
  4. •List row
  5. •Primary/secondary/icon buttons
  6. •Empty state
  7. •Loading skeleton
  8. •Error banner
  9. •Form field row
  10. •Chip/tag/pill

Full Reference

For complete implementation patterns, code recipes, design tokens, Liquid Glass details, and the full ADA review checklist:

See: swiftui-playbook.md