ar4mirez/uikit

UIKit Guide

Applies to: UIKit (iOS 12+), Swift 5.0+, Imperative UI, iOS/tvOS/Mac Catalyst

Core Principles

1. MVVM + Coordinator: Separate view logic (VC), presentation (ViewModel), and navigation (Coordinator)
2. Programmatic UI: Build views in code with Auto Layout; avoid storyboards for team projects
3. Thin View Controllers: View controllers configure views and bind to view models; no business logic
4. Protocol-Oriented Delegation: Use delegate protocols for callbacks; always declare delegates weak
5. Memory Safety: Use [weak self] in closures, cancel tasks in deinit, break retain cycles

Guardrails

View Controller Rules

• Keep view controllers under 200 lines (extract views, helpers, extensions)
• Override viewDidLoad once; call setupUI(), setupConstraints(), setupBindings()
• Never put networking or business logic in view controllers
• Always call super in lifecycle methods
• Use final class for all view controllers unless explicitly designed for subclassing
• Use required init?(coder:) with fatalError for programmatic-only controllers
• Mark @objc actions as private

Auto Layout Rules

• Always set translatesAutoresizingMaskIntoConstraints = false for programmatic views
• Use NSLayoutConstraint.activate([]) to batch-activate constraints
• Pin to safeAreaLayoutGuide for top/bottom content edges
• Use >= and <= constraints with priorities for flexible layouts
• Never set frames directly when using Auto Layout
• Use stack views (UIStackView) to reduce constraint count
• Set compressionResistance and hugging priorities explicitly when needed

Memory Management

• Use [weak self] in all escaping closures and Combine sinks
• Declare all delegates as weak var
• Cancel network tasks and Combine subscriptions in deinit
• Use [unowned self] only when the closure cannot outlive self (rare)
• Override prepareForReuse() in cells to clear state and cancel image loads

Naming Conventions

• View controllers: {Feature}ViewController (e.g., UserListViewController)
• View models: {Feature}ViewModel (e.g., UserListViewModel)
• Cells: {Item}Cell (e.g., UserCell)
• Coordinators: {Feature}Coordinator (e.g., UserCoordinator)
• Custom views: descriptive name (e.g., PrimaryButton, EmptyStateView)
• Protocols: {Name}Protocol or {Name}Delegate (e.g., UserServiceProtocol)

Project Structure

MyApp/
├── MyApp.xcodeproj
├── MyApp/
│   ├── Application/
│   │   ├── AppDelegate.swift
│   │   ├── SceneDelegate.swift
│   │   └── AppCoordinator.swift
│   ├── Features/
│   │   ├── Authentication/
│   │   │   ├── Controllers/
│   │   │   ├── ViewModels/
│   │   │   ├── Views/
│   │   │   └── Coordinator/
│   │   ├── Home/
│   │   │   ├── Controllers/
│   │   │   ├── ViewModels/
│   │   │   ├── Views/
│   │   │   └── Cells/
│   │   └── Profile/
│   ├── Core/
│   │   ├── Network/
│   │   ├── Storage/
│   │   ├── Extensions/
│   │   └── Utilities/
│   ├── Shared/
│   │   ├── Views/           # Reusable UI components
│   │   ├── Cells/           # Reusable cells
│   │   └── Protocols/       # Shared protocols
│   └── Resources/
│       ├── Assets.xcassets
│       └── Localizable.strings
├── MyAppTests/
└── MyAppUITests/

• Group by feature, not by type (Controllers/, ViewModels/ live inside each feature)
• Core/ for infrastructure (networking, storage, utilities)
• Shared/ for reusable UI components used across features
• One primary type per file, file named after the type

View Controller Lifecycle

Base View Controller Pattern

class BaseViewController: UIViewController {
    override func viewDidLoad() {
        super.viewDidLoad()
        setupUI()
        setupConstraints()
        setupBindings()
    }

    func setupUI() { view.backgroundColor = .systemBackground }
    func setupConstraints() { /* Override in subclasses */ }
    func setupBindings() { /* Override in subclasses */ }

    func showError(_ error: Error) {
        let alert = UIAlertController(
            title: "Error", message: error.localizedDescription, preferredStyle: .alert
        )
        alert.addAction(UIAlertAction(title: "OK", style: .default))
        present(alert, animated: true)
    }
}

Feature View Controller

import Combine

final class UserListViewController: BaseViewController {
    private let viewModel: UserListViewModel
    private var cancellables = Set<AnyCancellable>()
    weak var coordinator: UserCoordinator?

    private lazy var tableView: UITableView = {
        let table = UITableView(frame: .zero, style: .plain)
        table.translatesAutoresizingMaskIntoConstraints = false
        table.register(UserCell.self, forCellReuseIdentifier: UserCell.identifier)
        table.delegate = self
        table.dataSource = self
        table.rowHeight = UITableView.automaticDimension
        table.estimatedRowHeight = 80
        return table
    }()

    init(viewModel: UserListViewModel = UserListViewModel()) {
        self.viewModel = viewModel
        super.init(nibName: nil, bundle: nil)
    }

    required init?(coder: NSCoder) { fatalError("init(coder:) has not been implemented") }

    override func setupUI() {
        super.setupUI()
        title = "Users"
        view.addSubview(tableView)
    }

    override func setupConstraints() {
        NSLayoutConstraint.activate([
            tableView.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor),
            tableView.leadingAnchor.constraint(equalTo: view.leadingAnchor),
            tableView.trailingAnchor.constraint(equalTo: view.trailingAnchor),
            tableView.bottomAnchor.constraint(equalTo: view.bottomAnchor)
        ])
    }

    override func setupBindings() {
        viewModel.$users
            .receive(on: DispatchQueue.main)
            .sink { [weak self] _ in self?.tableView.reloadData() }
            .store(in: &cancellables)

        viewModel.$error
            .compactMap { $0 }
            .receive(on: DispatchQueue.main)
            .sink { [weak self] error in self?.showError(error) }
            .store(in: &cancellables)
    }

    override func viewDidLoad() {
        super.viewDidLoad()
        viewModel.loadUsers()
    }
}

MVVM View Model

import Foundation
import Combine

final class UserListViewModel {
    @Published private(set) var users: [User] = []
    @Published private(set) var isLoading = false
    @Published private(set) var error: Error?

    private let userService: UserServiceProtocol

    init(userService: UserServiceProtocol = UserService()) {
        self.userService = userService
    }

    func loadUsers() {
        isLoading = true
        error = nil
        Task { @MainActor in
            do { users = try await userService.fetchUsers() }
            catch { self.error = error }
            isLoading = false
        }
    }

    func deleteUser(at index: Int) {
        let user = users[index]
        users.remove(at: index)
        Task {
            do { try await userService.deleteUser(id: user.id) }
            catch { await MainActor.run { users.insert(user, at: index); self.error = error } }
        }
    }
}

Table Views and Collection Views

UITableView with DataSource/Delegate

extension UserListViewController: UITableViewDataSource {
    func tableView(_ tableView: UITableView, numberOfRowsInSection section: Int) -> Int {
        viewModel.users.count
    }

    func tableView(_ tableView: UITableView, cellForRowAt indexPath: IndexPath) -> UITableViewCell {
        guard let cell = tableView.dequeueReusableCell(
            withIdentifier: UserCell.identifier, for: indexPath
        ) as? UserCell else { return UITableViewCell() }
        cell.configure(with: viewModel.users[indexPath.row])
        return cell
    }
}

extension UserListViewController: UITableViewDelegate {
    func tableView(_ tableView: UITableView, didSelectRowAt indexPath: IndexPath) {
        tableView.deselectRow(at: indexPath, animated: true)
        coordinator?.showUserDetail(viewModel.users[indexPath.row])
    }
}

Diffable Data Source (iOS 13+)

enum Section { case main }
typealias DataSource = UICollectionViewDiffableDataSource<Section, Photo>
typealias Snapshot = NSDiffableDataSourceSnapshot<Section, Photo>

private func setupDataSource() {
    let registration = UICollectionView.CellRegistration<PhotoCell, Photo> { cell, _, photo in
        cell.configure(with: photo)
    }
    dataSource = DataSource(collectionView: collectionView) { cv, indexPath, photo in
        cv.dequeueConfiguredReusableCell(using: registration, for: indexPath, item: photo)
    }
}

private func applySnapshot(photos: [Photo], animating: Bool = true) {
    var snapshot = Snapshot()
    snapshot.appendSections([.main])
    snapshot.appendItems(photos)
    dataSource.apply(snapshot, animatingDifferences: animating)
}

Compositional Layout (iOS 13+)

private func createGridLayout() -> UICollectionViewLayout {
    let itemSize = NSCollectionLayoutSize(
        widthDimension: .fractionalWidth(1/3),
        heightDimension: .fractionalWidth(1/3)
    )
    let item = NSCollectionLayoutItem(layoutSize: itemSize)
    item.contentInsets = NSDirectionalEdgeInsets(top: 2, leading: 2, bottom: 2, trailing: 2)

    let groupSize = NSCollectionLayoutSize(
        widthDimension: .fractionalWidth(1.0),
        heightDimension: .fractionalWidth(1/3)
    )
    let group = NSCollectionLayoutGroup.horizontal(layoutSize: groupSize, subitems: [item])
    return UICollectionViewCompositionalLayout(section: NSCollectionLayoutSection(group: group))
}

Navigation Patterns

Coordinator Protocol

protocol Coordinator: AnyObject {
    var childCoordinators: [Coordinator] { get set }
    var navigationController: UINavigationController { get set }
    func start()
}

extension Coordinator {
    func addChild(_ coordinator: Coordinator) {
        childCoordinators.append(coordinator)
    }

    func removeChild(_ coordinator: Coordinator) {
        childCoordinators.removeAll { $0 === coordinator }
    }
}

App Coordinator

final class AppCoordinator: Coordinator {
    var childCoordinators: [Coordinator] = []
    var navigationController: UINavigationController
    private let authManager: AuthManager

    init(navigationController: UINavigationController, authManager: AuthManager = .shared) {
        self.navigationController = navigationController
        self.authManager = authManager
    }

    func start() {
        authManager.isAuthenticated ? showMainFlow() : showAuthFlow()
    }

    private func showAuthFlow() {
        let coordinator = AuthCoordinator(navigationController: navigationController)
        coordinator.delegate = self
        addChild(coordinator)
        coordinator.start()
    }

    private func showMainFlow() {
        let coordinator = MainTabCoordinator(navigationController: navigationController)
        addChild(coordinator)
        coordinator.start()
    }
}

Delegation Pattern

Delegate Protocol

protocol AddUserViewControllerDelegate: AnyObject {
    func addUserDidSave(_ controller: AddUserViewController, user: User)
    func addUserDidCancel(_ controller: AddUserViewController)
}

final class AddUserViewController: BaseViewController {
    weak var delegate: AddUserViewControllerDelegate?

    @objc private func saveTapped() {
        guard let user = buildUser() else { return }
        delegate?.addUserDidSave(self, user: user)
    }

    @objc private func cancelTapped() {
        delegate?.addUserDidCancel(self)
    }
}

Custom Cell Pattern

final class UserCell: UITableViewCell {
    static let identifier = "UserCell"

    private let nameLabel: UILabel = {
        let label = UILabel()
        label.translatesAutoresizingMaskIntoConstraints = false
        label.font = .preferredFont(forTextStyle: .headline)
        return label
    }()

    override init(style: UITableViewCell.CellStyle, reuseIdentifier: String?) {
        super.init(style: style, reuseIdentifier: reuseIdentifier)
        setupUI()
    }

    required init?(coder: NSCoder) { fatalError("init(coder:) has not been implemented") }

    private func setupUI() {
        contentView.addSubview(nameLabel)
        NSLayoutConstraint.activate([
            nameLabel.leadingAnchor.constraint(equalTo: contentView.leadingAnchor, constant: 16),
            nameLabel.trailingAnchor.constraint(equalTo: contentView.trailingAnchor, constant: -16),
            nameLabel.centerYAnchor.constraint(equalTo: contentView.centerYAnchor)
        ])
    }

    func configure(with user: User) { nameLabel.text = user.name }

    override func prepareForReuse() {
        super.prepareForReuse()
        nameLabel.text = nil
    }
}

Testing

View Controller Tests

import XCTest
@testable import MyApp

final class UserListViewControllerTests: XCTestCase {
    var sut: UserListViewController!
    var mockViewModel: MockUserListViewModel!

    override func setUp() {
        super.setUp()
        mockViewModel = MockUserListViewModel()
        sut = UserListViewController(viewModel: mockViewModel)
        sut.loadViewIfNeeded()
    }

    override func tearDown() {
        sut = nil; mockViewModel = nil
        super.tearDown()
    }

    func test_viewDidLoad_loadsUsers() {
        XCTAssertTrue(mockViewModel.loadUsersCalled)
    }

    func test_tableView_rowCount_matchesUsers() {
        mockViewModel.users = [User.stub(), User.stub()]
        let count = sut.tableView(sut.tableView, numberOfRowsInSection: 0)
        XCTAssertEqual(count, 2)
    }
}

Testing Standards

• Use protocol-based mocks injected via initializer
• Call loadViewIfNeeded() to trigger viewDidLoad without displaying
• Test data source methods directly on the view controller
• Test navigation by verifying coordinator method calls
• Test view model state changes with Combine expectations
• Coverage target: >80% for view models, >60% for view controllers

Commands

xcodebuild -scheme MyApp -sdk iphonesimulator build   # Build
xcodebuild test -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 15'
swift format .                                          # Format
swiftlint                                               # Lint

Best Practices

• Architecture: MVVM + Coordinator; thin view controllers; dependency injection via protocols
• Performance: Reuse cells with prepareForReuse(); async image loading; diffable data sources; profile with Instruments
• Accessibility: Dynamic Type (preferredFont); VoiceOver labels; semantic colors (.label, .systemBackground)
• Appearance: Configure UINavigationBarAppearance and UITabBarAppearance in AppDelegate

References

For detailed patterns and examples, see:

• references/patterns.md -- Coordinator, custom views, animations, Core Data, networking, testing

External References

• UIKit Documentation
• Modern Collection Views (WWDC 2020)
• Diffable Data Sources (WWDC 2019)
• Human Interface Guidelines