swiftui

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

Category	Requirement
Delight	Micro-delight at success moments only, never reduces clarity
Innovation	In discovery, state communication, simplifying complexity
Interaction	Predictable, direct, forgiving, platform-appropriate
Inclusivity	Dynamic Type XXL+, VoiceOver, no color-only meaning, reduced motion
Visuals	Consistent 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

Container	Use For
List	Large datasets, selection, swipe actions, edit mode
ScrollView + LazyVStack	Custom surfaces, cards, mixed content
Grid	Forms, settings, dense structured layouts
LazyVGrid	Responsive galleries
NavigationSplitView	iPad/Mac hierarchical apps
NavigationStack	Deep 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

Rule	Implementation
Body must be cheap	No sorting, filtering, formatting, I/O in body
Stable identity	ForEach(items, id: \.id) not \.self, no UUID() in body
Dependency hygiene	Keep @State local, pass Binding not whole model
Instrument	Use 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