---

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

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

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

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