building-ui

Building UI

Build repository UI through the existing model, design-system, and rendering seams. Treat this skill as the repository-specific authority when generic SwiftUI guidance conflicts with it. For example, use a Broadway stylesheet, not a generic constants enum. Use swiftui-pro alongside this skill for current SwiftUI API, performance, and platform guidance.

Start from the existing shape

1. Read the root AGENTS.md, then every AGENTS.md that scopes the files being changed. Local files retain module-specific product, dependency, and lifetime invariants.
2. Inspect the feature's existing views, view models, reusable components, Broadway root, stylesheet, preview fixtures, and snapshot declarations before designing another path.
3. Extend an existing view with a mode or shared subview when two surfaces express the same concept. Keep screen-specific registration and rendering declarations beside the represented screen.
4. Identify the narrowest layer that owns the behavior before editing UI.

Keep views presentational

• Put persistence, domain rules, detection, aggregation, cache policy, and side effects in Core/services. Put observable mirrors, lifecycle orchestration, and intent methods in a view model. Let a View render state and route intents.
• Extract an @Observable model or focused child type when a view begins to own system logic, an internal state machine, or unrelated behavioral areas.
• Model mutually dependent UI values as one enum or named value so invalid combinations cannot be represented.
• Bind directly to observable state. For a derived binding, expose a computed get/set property on the model and bind to it. Do not build Binding(get:set:) in a view.
• Keep previews and tests on the production data flow. Inject a protocol fake or production-shaped fixture instead of adding DEBUG state or a parallel refresh path to product code.
• Scope presentation-driven work to actual visibility. Key tasks by every identity-relevant input and let cancellation return before changing durable presentation state, emitting haptics, or publishing late UI updates.