uikit-expert

name

uikit-expert

description

Write, review, or improve UIKit code following best practices for view controller lifecycle, Auto Layout, collection views, navigation, animation, memory management, and modern iOS 18–26 APIs. Use when building new UIKit features, refactoring existing views or view controllers, reviewing code quality, adopting modern UIKit patterns (diffable data sources, compositional layout, cell configuration), or bridging UIKit with SwiftUI. Does not cover SwiftUI-only code.

UIKit Expert Skill

Overview

Use this skill to build, review, or improve UIKit features with correct lifecycle management, performant Auto Layout, modern collection view APIs, and safe navigation patterns. Prioritize native APIs, Apple's documented best practices, and performance-conscious patterns. This skill focuses on facts and best practices without enforcing specific architectural patterns (no MVVM/VIPER/Coordinator mandates).

Workflow Decision Tree

1) Review existing UIKit code

• Check view controller lifecycle usage — viewIsAppearing for geometry, viewDidLoad for setup only (see references/view-controller-lifecycle.md)
• Verify Auto Layout correctness — batch activation, no constraint churn, translatesAutoresizingMaskIntoConstraints (see references/auto-layout.md)
• Check collection/table view APIs — diffable data sources, stable identity, CellRegistration (see references/modern-collection-views.md)
• Verify cell configuration uses UIContentConfiguration, not deprecated textLabel (see references/cell-configuration.md)
• Check list scroll performance — prefetching, cell reuse cleanup, reconfigureItems (see references/list-performance.md)
• Verify navigation patterns — bar appearance all 4 slots, no concurrent transition crashes (see references/navigation-patterns.md)
• Check animation correctness — API selection, PropertyAnimator state machine, constraint animation (see references/animation-patterns.md)
• Audit memory management — [weak self], delegate ownership, Timer/CADisplayLink traps (see references/memory-management.md)
• Check concurrency safety — Task lifecycle, cancellation in viewDidDisappear (see references/concurrency-main-thread.md)
• If SwiftUI interop present — verify UIHostingController containment, sizingOptions (see references/uikit-swiftui-interop.md)
• Check image loading — downsampling, cell reuse race condition (cancel/clear/verify) (see references/image-loading.md)
• Verify keyboard handling — UIKeyboardLayoutGuide over manual notifications (see references/keyboard-scroll.md)
• Check trait handling and accessibility — registerForTraitChanges, Dynamic Type, VoiceOver (see references/adaptive-appearance.md)
• Validate modern API adoption and iOS 26+ availability handling (see references/modern-uikit-apis.md)

2) Improve existing UIKit code

• Replace geometry work in viewDidLoad with viewIsAppearing (see references/view-controller-lifecycle.md)
• Eliminate constraint churn — create once, toggle isActive or modify .constant (see references/auto-layout.md)
• Migrate from legacy UITableViewDataSource to diffable data sources (see references/modern-collection-views.md)
• Replace deprecated textLabel/detailTextLabel/imageView with UIContentConfiguration (see references/cell-configuration.md)
• Replace reloadItems with reconfigureItems for in-place cell updates (see references/list-performance.md)
• Fix navigation bar appearance — set all 4 appearance slots, use navigationItem not navigationBar (see references/navigation-patterns.md)
• Improve animations — use PropertyAnimator for gestures, correct constraint animation pattern (see references/animation-patterns.md)
• Fix retain cycles — add [weak self], cancel Tasks in viewDidDisappear, use block-based Timer (see references/memory-management.md)
• Migrate GCD to Swift concurrency — replace DispatchQueue.main.async with Task (see references/concurrency-main-thread.md)
• Suggest image downsampling when UIImage(data:) or full-resolution loading detected (as optional optimization, see references/image-loading.md)
• Replace keyboard notification handling with UIKeyboardLayoutGuide (see references/keyboard-scroll.md)
• Replace traitCollectionDidChange with registerForTraitChanges (see references/adaptive-appearance.md)
• Adopt iOS 26 APIs where appropriate — Observation, updateProperties(), .flushUpdates (see references/modern-uikit-apis.md)

3) Implement new UIKit feature

• Design data flow first: identify owned state, injected dependencies, and model layer
• Set up view controller lifecycle correctly — one-time setup in viewDidLoad, geometry in viewIsAppearing (see references/view-controller-lifecycle.md)
• Build Auto Layout with batch activation and zero churn (see references/auto-layout.md)
• Use modern collection view stack: DiffableDataSource + CompositionalLayout + CellRegistration (see references/modern-collection-views.md)
• Configure cells with UIContentConfiguration and configurationUpdateHandler (see references/cell-configuration.md)
• Implement prefetching and proper cell reuse cleanup for lists (see references/list-performance.md)
• Set up navigation with all 4 appearance slots and concurrent-transition guards (see references/navigation-patterns.md)
• Choose correct animation API for the use case (see references/animation-patterns.md)
• Use [weak self] in escaping closures, cancel Tasks in lifecycle methods (see references/memory-management.md)
• Use @MainActor correctly, store Task references (see references/concurrency-main-thread.md)
• If embedding SwiftUI — use full child VC containment for UIHostingController (see references/uikit-swiftui-interop.md)
• Downsample images for display, handle cell reuse race condition (see references/image-loading.md)
• Use UIKeyboardLayoutGuide for keyboard handling (see references/keyboard-scroll.md)
• Support Dynamic Type, VoiceOver, dark mode from the start (see references/adaptive-appearance.md)
• Gate iOS 26+ features with #available and provide sensible fallbacks (see references/modern-uikit-apis.md)

Core Guidelines

View Controller Lifecycle

• Use viewDidLoad for one-time setup: subviews, constraints, delegates — NOT geometry
• Use viewIsAppearing (back-deployed iOS 13+) for geometry-dependent work, trait-based layout, scroll-to-item
• viewDidLayoutSubviews fires multiple times — use only for lightweight layer frame adjustments
• viewWillAppear is limited to transition coordinator animations and balanced notification registration
• Always call super in every lifecycle override
• Child VC containment: addChild → addSubview → didMove(toParent:) — in that exact order
• Verify deallocation with deinit logging during development

Auto Layout

• Always set translatesAutoresizingMaskIntoConstraints = false on programmatic views
• Use NSLayoutConstraint.activate([]) — never individual .isActive = true
• Create constraints once, toggle isActive or modify .constant — never remove and recreate
• Never change priority from/to .required (1000) at runtime — use 999
• Animate constraints: update constant → call layoutIfNeeded() inside animation block on superview
• iOS 26+: use .flushUpdates option to simplify constraint animation
• Avoid deeply nested UIStackViews in reusable cells

Collection Views & Data Sources

• Use UICollectionViewDiffableDataSource with stable identifiers (UUID/database ID, not full model structs)
• Use reconfigureItems for content updates, reloadItems only when cell type changes
• Use applySnapshotUsingReloadData for initial population (bypasses diffing)
• Use UICollectionViewCompositionalLayout for any non-trivial layout
• Use UICollectionView.CellRegistration — no string identifiers, no manual casting
• Use UIContentConfiguration for cell content and UIBackgroundConfiguration for cell backgrounds
• Use configurationUpdateHandler for state-driven styling (selection, highlight)

Navigation

• Configure all 4 UINavigationBarAppearance slots (standard, scrollEdge, compact, compactScrollEdge)
• Set appearance on navigationItem (per-VC) in viewDidLoad, not on navigationBar in viewWillAppear
• Use setViewControllers(_:animated:) for deep links — not sequential push calls
• Guard against concurrent transitions — check transitionCoordinator before push/pop
• Set prefersLargeTitles once on the bar; use largeTitleDisplayMode per VC

Animation

• UIView.animate — simple one-shot animations; check finished in completion
• UIViewPropertyAnimator — gesture-driven, interruptible; respect state machine (inactive → active → stopped)
• CABasicAnimation — layer-only properties (cornerRadius, shadow, 3D transforms); set model value first
• iOS 17+ spring API: UIView.animate(springDuration:bounce:) aligns with SwiftUI
• Constraint animation: flush layout → update constant → animate layoutIfNeeded() on superview

Memory Management

• Default to [weak self] in all escaping closures
• Timer: use block-based API with [weak self], invalidate in viewWillDisappear
• CADisplayLink: use weak proxy pattern (no block-based API available)
• NotificationCenter: [weak self] in closure, remove observer in deinit
• Nested closures: re-capture [weak self] in stored inner closures
• Delegates: always weak var delegate: SomeDelegate? with AnyObject constraint
• Verify deallocation with deinit — if never called, a retain cycle exists

Concurrency

• UIViewController is @MainActor — all subclass methods are implicitly main-actor
• Store Task references, cancel in viewDidDisappear — not deinit
• Check Task.isCancelled before UI updates after await
• Task.detached does NOT inherit actor isolation — explicit MainActor.run needed for UI
• Never call DispatchQueue.main.sync from background — use await MainActor.run

UIKit–SwiftUI Interop

• UIHostingController: full child VC containment (addChild → addSubview → didMove), retain as stored property
• sizingOptions = .intrinsicContentSize (iOS 16+) for Auto Layout containers
• UIViewRepresentable: set mutable state in updateUIView, not makeUIView; guard against update loops
• UIHostingConfiguration (iOS 16+) for SwiftUI content in collection view cells

Image Loading

• Decoded bitmap size = width × height × 4 bytes (a 12MP photo = ~48MB RAM)
• Downsample with ImageIO at display size — never load full bitmap and resize
• iOS 15+: use byPreparingThumbnail(of:) or prepareForDisplay() for async decoding
• Cell reuse: cancel Task in prepareForReuse, clear image, verify identity on completion

Keyboard & Scroll

• Use UIKeyboardLayoutGuide (iOS 15+) — pin content bottom to view.keyboardLayoutGuide.topAnchor
• iPad: set followsUndockedKeyboard = true for floating keyboards
• Replace all manual keyboard notification handling with the layout guide

Adaptive Layout & Accessibility

• Use registerForTraitChanges (iOS 17+) instead of deprecated traitCollectionDidChange
• Dynamic Type: UIFont.preferredFont(forTextStyle:) + adjustsFontForContentSizeCategory = true
• Dark mode: use semantic colors (.label, .systemBackground); re-resolve CGColor on trait changes
• VoiceOver: set accessibilityLabel, accessibilityTraits, accessibilityHint on custom views
• Use UIAccessibilityCustomAction for complex list item actions

Quick Reference

View Controller Lifecycle Method Selection

Method	Use For
viewDidLoad	One-time setup: subviews, constraints, delegates
viewIsAppearing	Geometry-dependent work, trait-based layout, scroll-to-item
viewWillAppear	Transition coordinator animations only
viewDidLayoutSubviews	Lightweight layer frame adjustments (fires multiple times)
viewDidAppear	Start animations, analytics, post-appearance work
viewWillDisappear	Cancel tasks, invalidate timers, save state
viewDidDisappear	Final cleanup, cancel background work

Animation API Selection

API	Best For	Interactive	Off Main Thread
UIView.animate	Simple one-shot changes	No	No
UIViewPropertyAnimator	Gesture-driven, interruptible	Yes	No
CABasicAnimation	Layer properties, 3D transforms	Limited	Yes (Render Server)

Deprecated → Modern API Replacements

Deprecated / Legacy	Modern Replacement	Since
traitCollectionDidChange	registerForTraitChanges(_:handler:)	iOS 17
Keyboard notifications	UIKeyboardLayoutGuide	iOS 15
cell.textLabel / detailTextLabel	UIListContentConfiguration	iOS 14
register + string dequeue	UICollectionView.CellRegistration	iOS 14
reloadItems on snapshot	reconfigureItems	iOS 15
barTintColor / isTranslucent	UINavigationBarAppearance (4 slots)	iOS 13
UICollectionViewFlowLayout (complex)	UICollectionViewCompositionalLayout	iOS 13
Manual layoutIfNeeded() in animations	.flushUpdates option	iOS 26
Legacy app lifecycle	UIScene + SceneDelegate	Mandatory iOS 26
ObservableObject + manual invalidation	@Observable + UIObservationTrackingEnabled	iOS 18

Review Checklist

View Controller Lifecycle

• viewDidLoad contains NO geometry-dependent work
• Geometry/trait work is in viewIsAppearing, not viewWillAppear
• Every lifecycle override calls super
• Child VC uses correct containment sequence
• deinit is implemented for leak verification during development

Auto Layout

• translatesAutoresizingMaskIntoConstraints = false on all programmatic views
• Constraints activated via NSLayoutConstraint.activate([])
• No constraint removal/recreation — using isActive toggle or .constant modification
• No priority changes from/to .required (1000) at runtime
• No setNeedsLayout() inside layoutSubviews or viewDidLayoutSubviews (infinite loop)
• Constraint identifiers set for debugging

Collection Views

• Using diffable data source with stable identifiers (not full model structs)
• reconfigureItems for content updates, not reloadItems
• CellRegistration instead of string-based register/dequeue
• UIContentConfiguration instead of deprecated cell properties
• No duplicate identifiers in snapshot (BUG_IN_CLIENT crash)
• Self-sizing cells have unambiguous top-to-bottom constraint chain

Navigation

• All 4 UINavigationBarAppearance slots configured
• Appearance set on navigationItem in viewDidLoad, not navigationBar in viewWillAppear
• Concurrent transition guard in place
• prefersLargeTitles set once; largeTitleDisplayMode per VC

Animation

• Correct API chosen for use case (animate vs PropertyAnimator vs CA)
• UIViewPropertyAnimator state machine respected
• Constraint animation uses correct pattern (flush → update → animate)
• CAAnimation sets model value before adding animation
• Completion handlers check finished parameter

Memory Management

• [weak self] in all escaping closures
• Timers use block-based API with [weak self]; invalidated in viewWillDisappear
• Task references stored and cancelled in viewDidDisappear
• CADisplayLink uses weak proxy pattern
• Delegates declared as weak var on AnyObject-constrained protocol
• No strong self re-capture in nested stored closures

Concurrency

• Task.isCancelled checked after await before UI updates
• No Task.detached for UI work without explicit MainActor.run
• No redundant @MainActor on UIViewController subclasses (already inherited)
• No DispatchQueue.main.sync from background

Image Loading

• Images downsampled to display size (not loaded at full resolution)
• Cell image loading: cancel in prepareForReuse, clear image, verify identity
• NSCache sized by decoded bitmap bytes, not file size

UIKit–SwiftUI Interop

• UIHostingController retained as stored property (not local variable)
• UIHostingController uses full child VC containment (addChild → addSubview → didMove)
• updateUIView guards against infinite update loops with equality checks

Keyboard

• Using UIKeyboardLayoutGuide (iOS 15+) instead of keyboard notifications
• iPad: followsUndockedKeyboard = true on the layout guide

Adaptive & Accessibility

• registerForTraitChanges (iOS 17+) instead of traitCollectionDidChange
• Dynamic Type: preferredFont + adjustsFontForContentSizeCategory = true
• CGColor properties re-resolved on trait changes (layer.borderColor, shadowColor)
• Custom views have accessibilityLabel and accessibilityTraits
• UIAccessibilityCustomAction for complex list item actions

Modern APIs (iOS 26+)

• #available guards with sensible fallbacks for iOS 26+ features
• UIScene lifecycle adopted (mandatory for iOS 26 SDK)
• UIObservationTrackingEnabled considered for iOS 18+ targets

References

• references/view-controller-lifecycle.md — Lifecycle ordering, viewIsAppearing, child VC containment
• references/auto-layout.md — Batch activation, constraint churn, priority, animation, debugging
• references/modern-collection-views.md — Diffable data sources, compositional layout, CellRegistration
• references/cell-configuration.md — UIContentConfiguration, UIBackgroundConfiguration, configurationUpdateHandler
• references/list-performance.md — Prefetching, cell reuse, reconfigureItems, scroll performance
• references/navigation-patterns.md — Bar appearance, concurrent transitions, large titles, deep links
• references/animation-patterns.md — UIView.animate, UIViewPropertyAnimator, CAAnimation, springs
• references/memory-management.md — Retain cycles, [weak self], Timer/CADisplayLink/nested closure traps
• references/concurrency-main-thread.md — @MainActor, Task lifecycle, Swift 6, GCD migration
• references/uikit-swiftui-interop.md — UIHostingController, UIViewRepresentable, sizing, state bridging
• references/image-loading.md — Downsampling, decoded bitmap math, cell reuse race condition
• references/keyboard-scroll.md — UIKeyboardLayoutGuide, scroll view insets, iPad floating keyboard
• references/adaptive-appearance.md — Trait changes, Dynamic Type, dark mode, VoiceOver, accessibility
• references/modern-uikit-apis.md — Observation framework, updateProperties(), .flushUpdates, UIScene, Liquid Glass

Philosophy

This skill focuses on facts and best practices, not architectural opinions:

• We don't enforce specific architectures (e.g., MVVM, VIPER, Coordinator)
• We do encourage separating business logic for testability
• We optimize for correctness first, then performance
• We follow Apple's documented APIs and Human Interface Guidelines
• We use "suggest" or "consider" for optional optimizations
• We use "always" or "never" only for correctness issues