uikit-ui-common-setup

name	uikit-ui-common-setup
description	Use when writing or refactoring UIKit UI in this repo, especially Workflow/ViewController wiring, Controller/View components, SnapKit layout, Workspace/Dflat-driven UI state, Objective-C adapter responders, or app threading boundaries.

UIKit UI Common Setup

First Pass

• Read nearby app code before introducing a new shape.
• Prefer existing Draw Things / LocalCode UIKit patterns over new abstractions.
• Use rg / rg --files to find matching Workflow, ViewController, and Controller examples.

Workflow And ViewController

• UI screens are managed by Workflow objects.
• A Workflow owns the concrete UIViewController.
• Expose viewController when the workflow needs the concrete type, and viewControllable as the generic UIKit-facing UIViewController.
• UIViewController subclasses are views plus UIKit event handling only.
• Do not put business logic, persistence policy, generation logic, networking, model work, or off-main-thread work in a UIViewController.
• UIViewController sends events out through delegates. The Workflow handles them and sets properties back on the view controller.

Controller And View

• For shared business logic outside a workflow, use Controller & View.
• A controller is a plain Swift class, not NSObject and not a UIKit subclass.
• It owns one root UIView property, usually let view: UIView.
• Controllers are usually owned by workflows. Letting a view controller own one is only for lightweight, mostly animation-focused cases.

Layout And View Setup

• Use lazy vars for referenced views. Each lazy var configures that view and self-contained subviews.
• Put hierarchy assembly and cross-view SnapKit constraints inline in viewDidLoad or the controller initializer.
• In viewDidLoad or the controller initializer, do layout first, then action/delegate hookups.
• Do not create one-off configureXXX / setupXXX methods for view setup, layout, or action wiring.
• Domain helpers are fine when they express behavior or reusable construction, such as makeProjectMenu, updateSettingsSections, or didTapCollapseOrExpand.

One-Way Dataflow

• Persisted UI state should flow from Dflat / Workspace / workspace.dictionary observations into UI properties.
• Delegate callbacks should write source-of-truth state or call workflow/controller behavior, not directly mutate unrelated UI state.
• Even didSet-driven UI updates should be reached through the owning Workflow or real Controller when the state is not purely local view presentation.
• Keep view controllers as render targets: set properties on them; let them update UIKit controls.

Objective-C And UIKit Adapters

• A UIViewController already inherits from NSObject; using it for UIKit lifecycle/delegates is fine.
• Plain controllers must stay plain Swift classes.
• When a plain controller needs Objective-C delegation, target/action, or UIKit delegate conformance, create a nested responder such as Controller.ObjCResponder: NSObject.
• The responder forwards callbacks back to the controller; it does not own business logic.

Threads And Queues

• Do not use async / await in app UI code.
• UIViewController subclasses and views should only touch main-thread UIKit state.
• Workflow and Controller objects are the right places for off-main-thread behavior.
• Avoid creating private queues per workflow/controller. Reuse existing shared queues when behavior fits.
• Prefer one or two shared queues for broad work classes, like Draw Things' edit queue handling generation, tokenization, and related work.
• Create a new queue only when the behavior truly needs a separate serialization or QoS boundary. For rare fire-and-forget work, a global concurrent queue can be acceptable.