SwiftUI Excellence Playbook

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+)

• 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

• 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

List

ScrollView

LazyVStack

Grid

LazyVGrid

NavigationSplitView

NavigationStack

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

ForEach(items, id: \.id)

\.self

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